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Summary 


The Desk Manager provides the user access to desk accessories. A desk accessory is a 
"mini-application" that can be run at the same time as a Cortland application. 

The Desk Manager provides support for two types of desk accessory's: Classic Desk 
Accessories (CDA) and New Desk Accessories (NDA). 

Classic Desk Accessories are desk accessories that are designed to execute in a non¬ 
desktop, non-event based environment. Unlike NDAs, a classic accessory gets full control 
of the machine during what is basically an interrupt state (generated by a keypress). The 
desk accessory is responsible for saving any of the application's memory that it uses as 
well as handling all I/O. 

New Desk Accessories are Macintosh Style desk accessories that are designed to execute in 
a desktop, event based environment NDAs run in a window and get "control" when that 
window is the topmost window. Just what kind of control a NDA has is described below. 

How CDA's are Used 

A user activates a CDA from the CDA menu. The CDA menu is displayed by pressing 
OPEN APPLE-CONTROL-ESCAPE. Two CDA's are built into the system: 

Control Panel 
Alternate Display Mode 

Any others (up to eleven) are loaded from disk. From the CDA menu, a user can select any 
of the DA's currently in the system. The desk accessory is activated and retains control 
until it shuts down. When it shuts down, the Desk Manager re-displays the CDA Menu. 
Only when the user selects Quit from the CDA menu does the original application resume 
operation. 

When can the CDA Menu be displayed? 

The Desk manager gets control whenever the user presses OPEN-APPLE CONTROL- 
ESC. Before it displays the CDA Menu, it checks the system busy flag. If something in 
the system is busy, the Desk Manager schedules a wake-up with the scheduler. The next 
time the system flag is free, the scheduler will wake up the Desk Manager which then can 
display the CDA menu. This guarcntees that CDA's have all system resources available to 
them when they are called. 

Execution Environment 

Classic Desk Accessories have a single entry (activation) point When the CDA gets 
control, the processor is in full native mode (16-bit m and x registers). The desk accessory 
menu is still displayed on the screen in whatever was mode requested by the user (in the 
control panel). The CDA must execute the RTL in full native mode for the Desk Manager 
to work correctly. 

When the desk manager displays the CDA menu, it saves the text pages in bank 0 and 1, 
$E0 and $E1 along with pages 0 and 1 of bank 0 (system direct page and stack). (Only the 
screen holes used by the Desk Manager are preserved.) These parts of memory are 
restored by the Desk Manager when the user selects Quit from the CDA menu. Thus a 
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CDA can feel free to use almost all of this memory as it sees fit The exception is the stack. 
Since, the Desk Manager's return address is on the stack (along with other Desk Manager 
variables), the CDA cannot cut the stack back any farther than it is when it gets control. 

A CDA must take care using any other memory in the system that it does not already own. 
A CDA can use the Memory Manager to obtain additional memory outside "special 
memory", but it cannot rely on being able to obtain any more of bank 0 and 1. 

Form In Memory and On Disk 

Classic Desk Accessories have a simple form. They are load files kept on the system disk 
in the DESK.ACCS subdirectory of the SYSTEM directory and have a file type $B9. The 
CDA starts with an idetification section as follows. 

StartOfDA dc il'NameLength' ; this combined with the characters that 

dc c'Name of DA' ; follow make a ProDOS string 

dc i4’StartOfDACode' ; This is a pointer to the start of the code 

The identification structure contains the name of the desk accessory and a pointer to the 
activation routine. 


How NDAs are Used 

New Desk Accessories are loaded by the operating system at boot time. An application that 
wants to make NDA’s available to the user does not have to do a lot of work. If the 
Application uses TaskMaster, it need only make three calls: 

DeskS tartup to initialize the Desk Manager 

FixAppleMenu to put the list of NDAs in the Apple Menu 

DeskS hutdown to shut down the Desk Manager 

TaskMaster will handle opening NDAs in response to menu selections, calling SystemTask 
and SystemClick when appropriate. Calling SystemEdit when a selection is made from the 
Edit Menu, and closing a desk accessory in response to the Close item of the File Menu. 

Applications that do not use TaskMaster must do the following to support new desk 
accessories. 


call DeskS tartup 
call FixAppleMenu 
call OpenNDA 
call SystemTask 
call SystemClick 
call SystemEdit 

close an NDA 

DeskShutdown 


To initialize the Desk Manager. 

To put the list of NDAs in the Apple Menu 

When the user selects an NDA from the Apple Menu 

Frequently (at least every time through the event loop). 

When a MouseDown event occurs in a system window. 
When a desk accessory is active and the user selects undo, 
cut, copy, paste or clear from the edit menu. 

When the user selects close from the file menu. You can use 
CloseNDA or CloseNDAbyWinPtr to do this. 

To shut down the Desk Manager 
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Execution Environment 

NDAs have four entry points: open, close, action and init. For each of these entry points 
the processor is in Full Native Mode. There is no direct page available so the NDA must 
obtain it from the stack. The open routine returns a long word on the stack. The action 
routine is passed information in all three registers. 

A NDA can assume that the following tools are loaded and initialized: 

QuickDraw 
Event Manager 
Window Manager 
Menu Manager 
Control Manager 
Scrap Manager 
LineEdit 
Dialog Manager 
Print Manager 

(Note there may be others. This part is not well thought out yet). The NDA is responsible 
for saving and restoring important globals like the current graf port (other important globals 
will be added to this list as we think of them). 

Form In Memory and On Disk 

New Desk Accessories have a different form than CD As. They are still load files kept on 
the system disk in the DESK.ACCS subdirectory of the SYSTEM directory but they have a 
file type $B8 and The NDA starts with an identification section as follows. 

Pointer to the open routine 
Pointer to the close routine 
Pointer to the action routine 
Pointer to the init routine 
How often the NDA gets run codes 
Describes what events it wants 
The text which describes the menu item 


The open routine must return a pointer to its window on the stack. When it calls the open 
routine, the desk accessory manager puts 4 bytes of zero on the stack before it pushes the 
RTL address. 

The close routine has no inputs and no outputs. 

The action routine is passed the action code in the a register. When the action is to handle 
an event, the x and y registers contain a pointer to the event record (low word in x, high 
word in y). The possible action codes are: 

Event 1 The only events that can be passed to a DA are 

ButtonDown, ButtonUp, KeyDown, AutoKeyDown, 
Update and Activate. Update and Activate events for a 
desk accessory are always passed on. The first three 
are passed on only if the EventMask indicates they 
should be passed on. 


StartOfDA dc i4'PtrToOpen' 
dc i4'PtrToClose' 
dc i4'PtrToAction' 
dc i4'PtrToInit' 
dc i2'Period' 
dc i2'EventMask' 
dec' MenuLineNH**’ 


7 

? 

? 
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Run 2 

Cursor 3 


Menu 4 

Undo 5 

Cut 6 

Copy 7 

Paste 8 

Clear 9 


The time period specified has passed. 

This is passed to a desk accessory if it is the front 
window each time SystemTask is called. The purpose 
is to allow the desk accessory to change the cursor 
when it is over the NDA's window. 

This is passed to a desk accessory if an item from a 
system menu is selected. The item id is passed in the a 
register, the menu id is passed in the x register. 

This is passed to a desk accessory if the application 
determines that the user has selected one of these edit 
commands from Edit menu. The action call should 
return a boolean in the A-register indicating whether 
or not the the co mman d was handled. 


The InitRoutine is a routine that is called every time DeskStartup is called for each NDA 
that is installed. 


The Period field describes how often the DA should be called with the "Run" action code. 
A period of 1 is every 60th of a second. A period of 2 is every 30th of a second. A period 
of 60 is every second. A period of $FFFF is never. A period of 0 is as often as possible. 
The action routine is called with the "run" code from SystemTask. The application should 
be calling SystemTask every time through its event loop. 

The MenuLine is a line of text that will be passed to the Menu Manager to appear in the 
Apple Menu. The line must start with a waste character since the MenuManager puts 
something here. The line must also have a back slash in it (\) and an H followed by two 
place holder characters. These characters will be replaced with the menu item ID for the 
desk accessory when FixAppleMenu is called. 
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Desk Manager Routines 


The desk manager has a number of calls but very few that a user would make. These are 
described below. 


DABootlnit Internal routine called at boot time to initialize the DA 

manager. 


Stack Before Call 

I previous contents I 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 

DAStartup Call made by an application before it makes any other desk 

manager calls. 


Stack Before Call 

I previous contents I 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 


DAShutdown Call made by an application before shutdown if it has made 

any desk manager calls. 


Stack Before Call 

I previous contents I 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 


DAVersion Returns the version number of the Desk Manager. 

Stack Before Call 

I previous contents I 

I space for version I 

I k-SP 

Stack After Call 

I previous contents I 

I version number I 

I k-SP 


DAReset Resets the Desk Manager. 
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Stack Before Call 

I previous contents I 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 


DAStatus Returns whether or not the Desk Manager's startup call has 

been issued. 

Stack Before Call 

I previous contents I 

I space for boolean I 

I k-SP 

Stack After Call 

I previous contents I 

I boolean result I 

I k-SP 


State Save Calls 

The state saving calls are internal routines used by the desk manager to preserve the 
machine state. Careless use of any of these calls could prevent an application being 
interrupted from running when the current interrupt is over. 

SaveScm SaveScreen will save the 80-column text screens in bank 00, 

01, E0 and El. This new image of the screen will be used 
for subsequent calls to RestScreen. 

Stack Before Call 

I previous contents I 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 

An important thing to note is that only the screen holes used by the Desk Manager are 
preserved. 


RestScm RestoreScreen will restore the screen area saved by the Desk 

Manager. 


Stack Before Call 

I previous contents I 

I k-SP 

Stack After Call 
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I previous contents I 

I k-SP 

An important thing to note is that only the screen holes used by the Desk Manager are 
preserved. 


SaveAlJ Saves all the variables that the Desk Manager preserves 

when the CDA menu is activated. 


Stack Before Call 

I previous contents I 

I k-SP 


Stack After Cal! 

I previous contents I 

I k-SP 


RestAll Restores all the variables that the Desk Manager preserves 

when the CDA menu is activated. 


Stack Before Call 

I previous contents I 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 


InstallNDA 


Installs the new desk accessory in the system. 


Stack Before Cal) 

I previous contents I 

I handle to ID I handle pointing to ID structure of DA 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 


****«« mi* ■■ «n > 



Stack Before Call 

I previous contents 

I handle to ID 

I 


I 


I handle pointing to ID structure of DA 
k-SP 


Stack After Call 

I previous contents I 

I k-SP 


Classic Desk Accessory Routines 


ChooseCDA 


Activates the Desk Manager and displays the CDA 
menu. 


Stack Before Call 

I previous contents I 

I k-SP 

Stack After Cal) 

I previous contents I 

I k-SP 


ChooseCDA causes the Desk Manager to display the CDA Menu as if the user key stroke 
interupt has occured. I'm not sure there is any valid reason for a program to make this call. 


SetDAStrPtr 


Lets a program change the names of the Classic Desk 
Accessories. 


Stack Before Call 

I previous contents I 

I DA id num I 

I Pointer to Str I 

I k-SP 

Stack After Call 

I previous consents I 

I k-SP 


This routine is used to localize the desk accessories in ROM. It allows the built-in desk 
accessories to have different names. 


GetDAStrPtr 


Returns the pointer to the name string of a classic desk 
accessory. 


Stack Before Call 

I previous contents 
I space for result 
I DA id mm 

I 


I 

I 

I 

k-SP 
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Stack After Call 

I previous consents 
I pointer to DA str 
I 


I 

k-SP 



OpenNDA Opens the specified DA by ID number. 

Stack Before Call 

I previous contents 
I Space for R efNum 
I IDNum 

I 

Stack After Call 

I previous contents 
I ReJNum 

I k-SP 

This call is made when an application discovers that the user has selected an NDA from the 
Apple Menu. The ID Num passed is the same ID returned by the Menu Manager and set up 
by the FixAppleMenu call. 

CloseNDA Closes the specified DA. 

Stack Before Cal) 

I previous contents I 

I RefNum I 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 

The RefNum is the RefNum returned by the open call. This call is very similar to the call 
on the Macintosh. Like the Macintosh, it is unlikely to be used by an application since 
NDAs are closed when the mouse goes down in the QoseBox and SystemClick handles 
this. 

CloseNDAbyWinPtr Closes the NDA whose window pointer is equal to the one 

that is passed. 

Stack Before Cal) 

I previous contents I 

I WinPtr I POINTER 

I k*SP 

Stack After Call 

I previous contents I 

I k-SP 


I word 

I ID number returned from Menu Manager (word) 
k-SP 
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This call is handy when trying to close a desk accessory because the user chose close from 
the file menu. When the user chooses close, the application uses the FrontWindow call to 
see what window is to be closed. If the front window is not an application window, the 
application can pass the pointer to CloseNDAbyWinPtr. 

Possible Errors 

NotSysWindow This is returned when the window pointer is not the 

pointer to a window owned by a NDA. 

CloseAllNDAs Closes all open NDAs. 

No stack parameters. 


FixAppleMenu 


Adds the names of the NDAs to the Apple menu. 


Stack Before Call 

I previous contents 
I SuminglD 

I 


I 

I ID to use for first NDA (word) 
k-SP 


Stack After Call 

I previous contents I 

I k-SP 


This call is used to put the names of the currently installed NDAs in the Apple menu. They 
are appended to the Apple Menu and the ID of the first NDA name is the ID passed. The 
next NDA gets ID+1 and so on. 


GetNumNDAs Returns the number of NDAs currently installed. 


Stack Before Call 

I previous contents 
I Space for integer 
I 


I 

I word 
k-SP 


Stack After Call 

I previous contents I 

I Number of NDAs I integer 

I k-SP 


SystemClick Called when application detects mouse down in a system 

window. 

Stack Before Call 

I previous contents I 

I Ptr to EvtRecord I 

I Window Ptr I 

I FindWindow Result I 

I k-SP 
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Stack After Call 

I previous contents I 
I k-SP 

This call is slightly different than the equivalent Macintosh call. One additional input is 
passed on the stack. This additional input is the result of the FindWindow call (that is 
where in the system window the mouse when down). This is different because the Desk 
Manager has no way to find out this information unless it is passed by the application. 

Note: If the application is using TaskMaster, it never needs to make this call. TaskMaster 
does the work for it. 


SystemEdit 

Passes standard menu edits to system windows. 

Stack 

Before Call 


1 

1 

previous contents 
Space for result 

1 

1 

1 

EdhType 

1 Word 

1 


k-SP 

Stack 

After Call 


1 

previous contents 

1 

1 

1 

Processed Flag 

1 BOOLEAN 
k-SP 

The valid Edit Types are 


1 

Undo 


2 

Cut 


3 

. Copy 


4 

Paste 


5 

Clear 


The processed flag returns true if the top window is a system window and false otherwise. 

SystemTask 

Called periodically by an application to support Desk 
Accessories doing periodic actions. 

Suck 

Before Call 


1 

1 

prfwu contents 

1 

k-SP 

SUck 

After Call 


1 

1 

previous contents 

1 

k-SP 


For eack open desk accessory, SystemTask causes the accessory to perform the periodic 
action defined for it, if any such action was defined and if the proper time period has 
passed since the action was last performed. For example, a clock accessory can be defined 
such that the second hand is to move once every second; the periodic action for the 
accessory will be to move the second hand to the next position, and SystemTask will alert 
the accessory every second to perform that action. 
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Note: If the application is using TaskMaster, it never needs to make this call. TaskMaster 
does the work for it. 


SystemEvent 


This is the entry point the Event Manger uses to the Desk 
Manager. 


Stack Before Call 

I previous contents 

I space for boolean 

I Event What 

I Event Message 
I Event When 

I Event Where 

I Event Mods 

I 


I 

I word 
I word 
I long 
I long 

I point Qong) 
I word 
k-SP 


Stack After Call 

I previous contents I 

I boolean I 

I k-SP 


System Event returns true if the event is processed by a DA and false if it is to be sent on to 
the application. The CDA activation keystroke is processed in this way. 

Note: An application would never make this call. 


SystemMenu Called by the Menu Manager when a desk accessory adds a 

menu to the System Menu Bar and an item from it is 
selected. 

Stack Before Call 

I previous contents I 

I MenuID I 

I ItemID I 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 

Note: An application would never make this call. 
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Summary of Calls 


DeskBootlnit 
DeskStartup 
DeskShutdown 
Desk Version 
DeskReset 
DeskS tatus 

Siaie_Sa\mJCalls 

SaveScm 
RestS cm 
SaveAll 
RestAU 

Hons&KsmngSMs, 

InstallCDA 

InstallNDA 

Classic Desk Accessory-Calls 

ChooseCDA 

SetDAStrPtr 

GetDAStrPtr 


OpenNDA 

QoseNDA 

CloseNDAbyWinPtr 

Close A11ND As 

FixAppleMenu 

GetNumNDAs 

SystemClick 

SystemEdit 

SystemTask 

System Event 

SystemMenu 
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